SOLR-17697 Ref-guide documentation for new picocli commands by janhoy · Pull Request #4271 · apache/solr

janhoy · 2026-04-08T10:25:03Z

This is a WIP POC for auto generating CLI ref-guide docs for the new picoCli instrumented tools. The docs are auto generated using PicoCLI's ManPageGenerator, one ref-guide page per tool. Menus are also updated, and tools are cross-linked. The existing landig page "Solr Control Script Reference" is reduced from a huge all-in-one page to an overview page that introduces the CLI and links to the generated man-pages. This way, our docs will always stay in sync with the actual @picocli annotations in the code.

There are two gradle tasks added in this PR:

generateCliDocs - Regenerate CLI reference pages in pages/cli/ from picocli annotations.
checkCliDocsUpToDate - Verify that pages/cli/ CLI docs are in sync with picocli annotations - runs on check

Screenshot:

This is a draft, mostly AI generated, not reviewed in full. Need discussion about how we want the docs to be.

https://issues.apache.org/jira/browse/SOLR-17697

janhoy · 2026-04-08T10:42:25Z

+// end::picocli-generated-man-section-commands[]
+
+// tag::picocli-generated-man-section-exit-status[]
+// end::picocli-generated-man-section-exit-status[]


We could obviously add @picocli annotations to document exit status for all tools asl well... Not sure how useful it is. Guess for the assert tool it would be useful, and for the stop tool to signal success...

I added example and exit-code documentation to the status tool. Here is how it looks:

janhoy · 2026-04-08T10:57:38Z

+== Command Reference
+
+The table below lists all available `bin/solr` commands.
+Commands marked with (✓) have dedicated reference pages auto-generated from source annotations; others are documented inline below.


This section is temporary, not intended for release. I suppose this entire "landing page" needs to be re-written in a way that gives a good overview, without touching the details.

Question: Currently we have usage examples hand written in the ref-guide page. We could instead add usage examples for each tool either in the description field or footer field, or some custom annotation that we invent and tie in when generating docs:

@Command( name = "myapp", footerHeading = "%nExamples:%n", footer = { " # Basic usage", " myapp --input foo.txt", "", " # With options", " myapp --input foo.txt --verbose" } )

I think perhaps using footer for this purpose is a good approach, this way also the --help for each tool will print usage examples. I think we can sacrifice the current refguide URL link we have in all the footers. It can perhaps be included on the main bin/solr command only.

I like that idea. And the ref guide link is a bit of an oddity too anyway...

We have been caught many times with ref guide differences from reality in the docs.

Ok, I took a shot at generating (with LLM) usage examples for all the zk sub commands. See updated adoc pages. Example:

dsmiley · 2026-04-08T13:50:16Z

This way, our docs will always stay in sync with the actual @picocli annotations in the code.

Nice!

epugh · 2026-04-08T13:57:40Z

I want to say how much i like the zk nesting of sub commands. I started hacking on a configset command in our old framework, and it was a bummer how hard it was to do nested subcommands. I can imaginge bin/solr configset upload -blah -blah and bin/solr configset putfile -blah -lbah and that nesting nicely in the docs with picocli!

…generation # Conflicts: # solr/core/src/java/org/apache/solr/cli/ConfigSetDownloadTool.java # solr/core/src/java/org/apache/solr/cli/ConfigSetUploadTool.java # solr/core/src/java/org/apache/solr/cli/StatusTool.java # solr/core/src/java/org/apache/solr/cli/UpdateACLTool.java # solr/core/src/java/org/apache/solr/cli/ZkLsTool.java # solr/core/src/java/org/apache/solr/cli/ZkRmTool.java

…and -h removed

Remove some hacks in gradle

janhoy · 2026-05-15T10:50:50Z

Note that the global options -Vand -h are now not included in each man page, much better (as a result of another PR that tailored the global options). I'll merge this into the feature branch any time now, and then we can continue iterating on that branch.

epugh · 2026-05-15T12:15:22Z


 The only reason you will likely need to change the `antora.template.yml` is if you are introducing new variables for dependency versions.

+== Auto-generated CLI Reference Pages


So, it's funny what things we check into source code that are generated and what are not (SolrJ endpoints from OpenAPI annotations for example). I just ran the task to generate the cli pages and it went super fast.. What value are we getting by checking them into source code? I don't have a super strong opinon one way or the other, more of an observation.

Checking them in gives less "magic" and will also help surface unintended CLI contract edites in tools as the PR will fail precommit, needing to re-generate docs. Then one can review if the change was intended and back-compat before calling generateCliDocs...

epugh · 2026-05-15T12:19:52Z

+=== Adding docs for a new tool
+
+The new command will automatically appear in the generated pages and the navigation when running `gradlew generateCliDocs`.
+You will need to tie it in to the `solr-control-script-reference.adoc` yourself.


Hopefully we rework solr-control-script-reference.adoc.... I see the table you added flagging which have autogenerated links. At a minimum, we should eliminate the listing of parameters to each command that exist in solr-control-script-reference.adoc and lean into using the generated docs. I don't know if that is part of this PR or it's own?

Yes, the control-script-reference page has still more work to do. I'll add another check box in the feature-branch PR for it...

epugh · 2026-05-15T12:21:18Z

+    exitCodeListHeading = "%nExit Codes:%n",
+    exitCodeList = {
+      "0:Collection or core deleted successfully.",
+      "1:Failed to delete; collection or core may not exist, or Solr may not be running."


wow... actual documentation of return codes! Helpful for folks writing automation.

Absolutely. Made me think about return codes a bit as well. Such as for solr stop. It will actually return 1 (failure) if solr was not already running. But perhaps it should be differentiated to returning

0 if solr was running and successfully stopped

1 if solr was not running

2 if there was a syntax error in the command

3 if solr was running but we could not stop it

This is out of scope for this PR, but I'd love it if documenting exit codes in picocli would lead to other PRs to clean up in our exit code behavior...

epugh · 2026-05-15T12:22:35Z

+    },
+    footerHeading = "%nExamples:%n",
+    footer = {
+      "  # Create a collection in SolrCloud mode",


do we still need to litter in SolrCloud mode everywhere? Or... Create a collection in SolrCloud mode and a core in User Managed mode? (sigh)...

i wonder..... Should we introduce a bin/solr core create -c myCore and keep bin/solr create -c myCollection as solr cloud? are there use cases where folks want to work with a specific core while in solr cloud mode? This is a bit off topic.

Good catch, the createTool is also for standalone. So this should probably be fixed.

I was impatient and mergd doc branch into feature branch. So will include this in a fixup commit shortly

epugh · 2026-05-15T12:24:46Z

-@CommandLine.Command(name = "start", description = "Starts Solr in standalone or SolrCloud mode.")
+@CommandLine.Command(
+    name = "start",
+    description = "Starts Solr in standalone or SolrCloud mode.",


standalone --> user-managed ? the switch is --user-managed. I dislike the term user managed, but it is what we agreed...... "Disagree and commit' ;-)

Will fix in followup commit to feature branch. I also caught a bug in the last example, where Claude had constructed this impossible command:

# Start in standalone mode with an external ZooKeeper bin/solr start --user-managed -z localhost:2181/solr

HAHA - user managed with zookeeper 🤣

SOLR-17697 Ref-guide documentation for new picocli commands

d6812b1

janhoy marked this pull request as draft April 8, 2026 10:25

github-actions Bot added documentation Improvements or additions to documentation tool:build labels Apr 8, 2026

janhoy mentioned this pull request Apr 8, 2026

SOLR-17697 Use picocli instead of commons-cli #3254

Draft

41 tasks

janhoy requested review from dsmiley and epugh April 8, 2026 10:35

janhoy commented Apr 8, 2026

View reviewed changes

Comment thread solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc

janhoy commented Apr 8, 2026

View reviewed changes

Comment thread solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc Outdated

janhoy commented Apr 8, 2026

View reviewed changes

Add dev-docs

e46d297

janhoy commented Apr 8, 2026

View reviewed changes

Comment thread solr/solr-ref-guide/build.gradle Outdated

Fix synopsis by printing it in a code block

dd530d5

janhoy added 3 commits April 9, 2026 02:47

Fix xref links, while still using 'bin/solr'

6c827df

Add blank comment line before DO NOT EDIT notice

87778c8

Added examples in annotations for zk sub commands

13dfa3a

github-actions Bot added the cat:cli label May 15, 2026

janhoy added 4 commits May 15, 2026 12:08

Document exit codes and examples on "status" tool

2a758f1

Re-generate docs with create and delete tools, and global options -V …

84cef6d

…and -h removed

Fix bin/solr vs solr.

e503573

Remove some hacks in gradle

janhoy marked this pull request as ready for review May 15, 2026 10:50

janhoy added 4 commits May 15, 2026 12:55

Add example and exitcode docs to more tools

4a76b3f

Revert exit code docs for "stop" command

0ba6a1c

Update docs for UpdateACLTool

0ad7ee8

Re-generated cli docs

9bc2ba3

janhoy merged commit f6d6f5f into apache:jira/SOLR-17697-picocli May 15, 2026
1 check passed

janhoy deleted the feature/picocli-cli-docs-generation branch May 15, 2026 12:21

epugh reviewed May 15, 2026

View reviewed changes


		The only reason you will likely need to change the `antora.template.yml` is if you are introducing new variables for dependency versions.

		== Auto-generated CLI Reference Pages

Conversation

janhoy commented Apr 8, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dsmiley commented Apr 8, 2026

Uh oh!

epugh commented Apr 8, 2026

Uh oh!

janhoy commented May 15, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janhoy May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

janhoy May 15, 2026 •

edited

Loading